home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / dgegs.z / dgegs
Encoding:
Text File  |  2002-10-03  |  9.7 KB  |  265 lines
  1.  
  2.  
  3.  
  4. DDDDGGGGEEEEGGGGSSSS((((3333SSSS))))                                                            DDDDGGGGEEEEGGGGSSSS((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DGEGS - routine is deprecated and has been replaced by routine DGGES
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      SUBROUTINE DGEGS( JOBVSL, JOBVSR, N, A, LDA, B, LDB, ALPHAR, ALPHAI,
  13.                        BETA, VSL, LDVSL, VSR, LDVSR, WORK, LWORK, INFO )
  14.  
  15.          CHARACTER     JOBVSL, JOBVSR
  16.  
  17.          INTEGER       INFO, LDA, LDB, LDVSL, LDVSR, LWORK, N
  18.  
  19.          DOUBLE        PRECISION A( LDA, * ), ALPHAI( * ), ALPHAR( * ), B(
  20.                        LDB, * ), BETA( * ), VSL( LDVSL, * ), VSR( LDVSR, * ),
  21.                        WORK( * )
  22.  
  23. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  24.      These routines are part of the SCSL Scientific Library and can be loaded
  25.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  26.      directs the linker to use the multi-processor version of the library.
  27.  
  28.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  29.      4 bytes (32 bits). Another version of SCSL is available in which integers
  30.      are 8 bytes (64 bits).  This version allows the user access to larger
  31.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  32.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  33.      only one of the two versions; 4-byte integer and 8-byte integer library
  34.      calls cannot be mixed.
  35.  
  36. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  37.      This routine is deprecated and has been replaced by routine DGGES. DGEGS
  38.      computes for a pair of N-by-N real nonsymmetric matrices A, B:  the
  39.      generalized eigenvalues (alphar +/- alphai*i, beta), the real Schur form
  40.      (A, B), and optionally left and/or right Schur vectors (VSL and VSR).
  41.  
  42.      (If only the generalized eigenvalues are needed, use the driver DGEGV
  43.      instead.)
  44.  
  45.      A generalized eigenvalue for a pair of matrices (A,B) is, roughly
  46.      speaking, a scalar w or a ratio  alpha/beta = w, such that  A - w*B is
  47.      singular.  It is usually represented as the pair (alpha,beta), as there
  48.      is a reasonable interpretation for beta=0, and even for both being zero.
  49.      A good beginning reference is the book, "Matrix Computations", by G.
  50.      Golub & C. van Loan (Johns Hopkins U. Press)
  51.  
  52.      The (generalized) Schur form of a pair of matrices is the result of
  53.      multiplying both matrices on the left by one orthogonal matrix and both
  54.      on the right by another orthogonal matrix, these two orthogonal matrices
  55.      being chosen so as to bring the pair of matrices into (real) Schur form.
  56.  
  57.      A pair of matrices A, B is in generalized real Schur form if B is upper
  58.      triangular with non-negative diagonal and A is block upper triangular
  59.      with 1-by-1 and 2-by-2 blocks.  1-by-1 blocks correspond to real
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDGGGGEEEEGGGGSSSS((((3333SSSS))))                                                            DDDDGGGGEEEEGGGGSSSS((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      generalized eigenvalues, while 2-by-2 blocks of A will be "standardized"
  75.      by making the corresponding elements of B have the form:
  76.              [  a  0  ]
  77.              [  0  b  ]
  78.  
  79.      and the pair of corresponding 2-by-2 blocks in A and B will have a
  80.      complex conjugate pair of generalized eigenvalues.
  81.  
  82.      The left and right Schur vectors are the columns of VSL and VSR,
  83.      respectively, where VSL and VSR are the orthogonal matrices which reduce
  84.      A and B to Schur form:
  85.  
  86.      Schur form of (A,B) = ( (VSL)**T A (VSR), (VSL)**T B (VSR) )
  87.  
  88.  
  89. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  90.      JOBVSL  (input) CHARACTER*1
  91.              = 'N':  do not compute the left Schur vectors;
  92.              = 'V':  compute the left Schur vectors.
  93.  
  94.      JOBVSR  (input) CHARACTER*1
  95.              = 'N':  do not compute the right Schur vectors;
  96.              = 'V':  compute the right Schur vectors.
  97.  
  98.      N       (input) INTEGER
  99.              The order of the matrices A, B, VSL, and VSR.  N >= 0.
  100.  
  101.      A       (input/output) DOUBLE PRECISION array, dimension (LDA, N)
  102.              On entry, the first of the pair of matrices whose generalized
  103.              eigenvalues and (optionally) Schur vectors are to be computed.
  104.              On exit, the generalized Schur form of A.  Note: to avoid
  105.              overflow, the Frobenius norm of the matrix A should be less than
  106.              the overflow threshold.
  107.  
  108.      LDA     (input) INTEGER
  109.              The leading dimension of A.  LDA >= max(1,N).
  110.  
  111.      B       (input/output) DOUBLE PRECISION array, dimension (LDB, N)
  112.              On entry, the second of the pair of matrices whose generalized
  113.              eigenvalues and (optionally) Schur vectors are to be computed.
  114.              On exit, the generalized Schur form of B.  Note: to avoid
  115.              overflow, the Frobenius norm of the matrix B should be less than
  116.              the overflow threshold.
  117.  
  118.      LDB     (input) INTEGER
  119.              The leading dimension of B.  LDB >= max(1,N).
  120.  
  121.      ALPHAR  (output) DOUBLE PRECISION array, dimension (N)
  122.              ALPHAI  (output) DOUBLE PRECISION array, dimension (N) BETA
  123.              (output) DOUBLE PRECISION array, dimension (N) On exit,
  124.              (ALPHAR(j) + ALPHAI(j)*i)/BETA(j), j=1,...,N, will be the
  125.              generalized eigenvalues.  ALPHAR(j) + ALPHAI(j)*i, j=1,...,N  and
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDGGGGEEEEGGGGSSSS((((3333SSSS))))                                                            DDDDGGGGEEEEGGGGSSSS((((3333SSSS))))
  137.  
  138.  
  139.  
  140.              BETA(j),j=1,...,N  are the diagonals of the complex Schur form
  141.              (A,B) that would result if the 2-by-2 diagonal blocks of the real
  142.              Schur form of (A,B) were further reduced to triangular form using
  143.              2-by-2 complex unitary transformations.  If ALPHAI(j) is zero,
  144.              then the j-th eigenvalue is real; if positive, then the j-th and
  145.              (j+1)-st eigenvalues are a complex conjugate pair, with
  146.              ALPHAI(j+1) negative.
  147.  
  148.              Note: the quotients ALPHAR(j)/BETA(j) and ALPHAI(j)/BETA(j) may
  149.              easily over- or underflow, and BETA(j) may even be zero.  Thus,
  150.              the user should avoid naively computing the ratio alpha/beta.
  151.              However, ALPHAR and ALPHAI will be always less than and usually
  152.              comparable with norm(A) in magnitude, and BETA always less than
  153.              and usually comparable with norm(B).
  154.  
  155.      VSL     (output) DOUBLE PRECISION array, dimension (LDVSL,N)
  156.              If JOBVSL = 'V', VSL will contain the left Schur vectors.  (See
  157.              "Purpose", above.)  Not referenced if JOBVSL = 'N'.
  158.  
  159.      LDVSL   (input) INTEGER
  160.              The leading dimension of the matrix VSL. LDVSL >=1, and if JOBVSL
  161.              = 'V', LDVSL >= N.
  162.  
  163.      VSR     (output) DOUBLE PRECISION array, dimension (LDVSR,N)
  164.              If JOBVSR = 'V', VSR will contain the right Schur vectors.  (See
  165.              "Purpose", above.)  Not referenced if JOBVSR = 'N'.
  166.  
  167.      LDVSR   (input) INTEGER
  168.              The leading dimension of the matrix VSR. LDVSR >= 1, and if
  169.              JOBVSR = 'V', LDVSR >= N.
  170.  
  171.      WORK    (workspace/output) DOUBLE PRECISION array, dimension (LWORK)
  172.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  173.  
  174.      LWORK   (input) INTEGER
  175.              The dimension of the array WORK.  LWORK >= max(1,4*N).  For good
  176.              performance, LWORK must generally be larger.  To compute the
  177.              optimal value of LWORK, call ILAENV to get blocksizes (for
  178.              DGEQRF, DORMQR, and DORGQR.)  Then compute:  NB  -- MAX of the
  179.              blocksizes for DGEQRF, DORMQR, and DORGQR The optimal LWORK is
  180.              2*N + N*(NB+1).
  181.  
  182.              If LWORK = -1, then a workspace query is assumed; the routine
  183.              only calculates the optimal size of the WORK array, returns this
  184.              value as the first entry of the WORK array, and no error message
  185.              related to LWORK is issued by XERBLA.
  186.  
  187.      INFO    (output) INTEGER
  188.              = 0:  successful exit
  189.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  190.              = 1,...,N:  The QZ iteration failed.  (A,B) are not in Schur
  191.              form, but ALPHAR(j), ALPHAI(j), and BETA(j) should be correct for
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. DDDDGGGGEEEEGGGGSSSS((((3333SSSS))))                                                            DDDDGGGGEEEEGGGGSSSS((((3333SSSS))))
  203.  
  204.  
  205.  
  206.              j=INFO+1,...,N.  > N:  errors that usually indicate LAPACK
  207.              problems:
  208.              =N+1: error return from DGGBAL
  209.              =N+2: error return from DGEQRF
  210.              =N+3: error return from DORMQR
  211.              =N+4: error return from DORGQR
  212.              =N+5: error return from DGGHRD
  213.              =N+6: error return from DHGEQZ (other than failed iteration)
  214.              =N+7: error return from DGGBAK (computing VSL)
  215.              =N+8: error return from DGGBAK (computing VSR)
  216.              =N+9: error return from DLASCL (various places)
  217.  
  218. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  219.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  220.  
  221.      This man page is available only online.
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.